From 85d4a5abc7c7b1a87b9eb118d1216ead0c00b3ec Mon Sep 17 00:00:00 2001 From: Kristian Rietveld Date: Thu, 11 Aug 2011 10:42:29 +0200 Subject: [PATCH] GtkTreeModel: add more detailed documentation on reference counting --- gtk/gtktreemodel.c | 41 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c index 26f6d73f86..02ea9c9a4f 100644 --- a/gtk/gtktreemodel.c +++ b/gtk/gtktreemodel.c @@ -197,6 +197,36 @@ * * * + * The #GtkTreeModel interface contains two methods for reference + * counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node(). + * These two methods are optional to implement. The reference counting + * is meant as a way for views to let models know when nodes are being + * displayed. #GtkTreeView will take a reference on a node when it is + * visible, which means the node is either in the toplevel or expanded. + * Being displayed does not mean that the node is currently directly + * visible to the user in the viewport. Based on this reference counting + * scheme a caching model, for example, can decide whether or not to cache + * a node based on the reference count. A file-system based model would + * not want to keep the entire file hierarchy in memory, but just the + * folders that are currently expanded in every current view. + * + * When working with reference counting, the following rules must be taken + * into account: + * + * Never take a reference on a node without owning a + * reference on its parent. This means that all parent nodes of a referenced + * node must be referenced as well. + * Outstanding references on a deleted node are not released. + * This is not possible because the node has already been deleted by the + * time the row-deleted signal is received. + * + * Models are not obligated to emit a signal on rows of + * which none of its siblings are referenced. To phrase this differently, + * signals are only required for levels in which nodes are referenced. For + * the root level however, signals must be emitted at all times (however the + * root level is always referenced when any view is attached). + * + * */ #define INITIALIZE_TREE_ITER(Iter) \ @@ -1615,9 +1645,11 @@ gtk_tree_model_iter_parent (GtkTreeModel *tree_model, * * This function is primarily meant as a way for views to let * caching models know when nodes are being displayed (and hence, - * whether or not to cache that node). For example, a file-system - * based model would not want to keep the entire file-hierarchy in - * memory, just the sections that are currently being displayed by + * whether or not to cache that node). Being displayed means a node + * is in an expanded branch, regardless of whether the node is currently + * visible in the viewport. For example, a file-system based model + * would not want to keep the entire file-hierarchy in memory, + * just the sections that are currently being displayed by * every current view. * * A model should be expected to be able to get an iter independent @@ -1824,6 +1856,9 @@ gtk_tree_model_row_has_child_toggled (GtkTreeModel *tree_model, * This should be called by models after a row has been removed. * The location pointed to by @path should be the location that * the row previously was at. It may not be a valid location anymore. + * + * Nodes that are deleted are not unreffed, this means that any + * outstanding references on the deleted node should not be released. */ void gtk_tree_model_row_deleted (GtkTreeModel *tree_model, -- 2.30.2